
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{JEdifClockDomain}
JEdifClockDomain is a .jedif based tool to analyze FPGA designs to obtain
information about the clock(s). The tool first identifies all clocks in a
design. This information is then used to optionally display other information,
such as classifying Xilinx primitives into one or more domains, showing clock
crossings, etc.

Several different options can be specified on the command line in any order.
This section describes each of these options in detail.

\begin{verbatim}
> java edu.byu.ece.edif.jedif.JEdifClockDomain
Options:
  [-h|--help]
  [-v|--version]

  <input_file>
  [(-o|--output) <output_file>]

  [--domain domain1,domain2,...,domainN]
  [--show_no_domain]
  [--show_clock_crossings show_clock_crossings1,show_clock_crossings2,...,show_clock_crossingsN ]
  [--create_dotty_graph create_dotty_graph1,create_dotty_graph2,...,create_dotty_graphN ]
  [--show_cells]
  [--show_nets]
  [--show_synchronous]
  [--show_asynchronous]
  [--show_gated_clocks]
  [--show_asynchronous_resets]
  [--show_asynchronous_reset_cells]
  [--do_scc_analysis]
  [--no_iob_feedback]
\end{verbatim}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{File options: input, output, etc.}

\subsubsection{\texttt{<input\_file>}}
Filename and path to the EDIF source file containing the top-level cell to be
analyzed. This is the only required parameter.

\subsubsection{\texttt{(-o) <output\_file>}}
Filename and path for the output of the tool.

Default: stdout

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Display Options}
By default, all clocks in the design are displayed and nothing else. The
following options determine which additional information to display (if any).
For example, if the option  \texttt{--do\_scc\_analysis} is not specified, the
SCC algorithms will not run, decreasing runtime.

\subsubsection{\texttt{--domain}}
This option allows the user to specify which domain(s) to display.  This option
alone doesn't display any information, but acts as a filter for other options. 
The options affected by the value of this option are:
\texttt{--show\_cells, --show\_nets, --show\_synchronous, --show\_asynchronous}.
If any of these options are specified, only information for items in the
specified domain(s) is displayed. The clock domain names are case-insensitive.

For example, if the design conatins $2$ clocks (clkA and clkB) and the user
wishes to display all cells in domain clkA, the following should be run:

java edu.byu.ece.edif.jedif.JEdifClockDomain myDesign.edf \texttt{--domain clka
--show\_cells}

\subsubsection{\texttt{--show\_no\_domain}}
This option is used to include those items which don't belong to a domain. As
with the previous option, this option applies only to the following options:
\texttt{--show\_cells, --show\_nets, --show\_synchronous, --show\_asynchronous}.
An example of a cell not in a domain is an IBUF, since it is not driven by
sequential logic.

\subsubsection{\texttt{--show\_clock\_crossings clk$1$,clk$2$}}
Display all clk$1$ to clk$2$ clock crossings in the design.  A clock crossing is
defined as a net driving an input port of a sequential cell (e.g. flip-flop), 
where the net's domain differs from the sequential cell's domain.  The string
`all' can be used as a wildcard for all domains.  For example,
\texttt{--show\_clock\_crossings all,clk$1$} will display all clock crossing
from any domain to clk$1$.  Likewise, \texttt{--show\_clock\_crossings
clk$1$,all} will display all clock crossings from clk$1$ to any other domain. 
Also, \texttt{--show\_clock\_crossings all,all} can be used to show all clock
crossings of all domains.  More than one set of clock domains can be specified,
but the number of domains given must be a multiple of two.  For example,
\texttt{--show\_clock\_crossings clk$1$,clk$2$,clk$2$,clk$1$} would show all
crossings from clk$1$ to clk$2$ and from clk$2$ to clk$1$.

Example output from using this option is below:
\begin{verbatim}
clk1 to clk2 (1 crossings)
  RAM(RAMB4_S1_S1) [rsta] Net:rstZ0 Driver:[rst (FD)]
\end{verbatim}
The interpretation of this output is that the `rsta' port of a cell named RAM of
type RAMB$4$\_S$1$\_S$1$ is driven by a cell named `rst' of type FD.  The net
connecting the cells is rstZ$0$. Since this is a clk$1$ to clk$2$ crossing, the
RAM is in the clk$2$ domain and the FD is in the clk$1$ domain.

\subsubsection{\texttt{--create\_dotty\_graph cell,port}}
Generate a dotty graph representation of ``cell'' and it's predecessors.  This
may be of particular interest when a clock crossing occurs that is not flip-flop
to flip-flop. This option creates a graph starting at the cell given as a
parameter.  The graph contains predecessors only through the specified port. 
For example, if port ``d'' is chosen for a flip-flop, the clock resource will
not be shown in the graph.  The graph extends back until another synchronous
element is found, or until no predecessors remain.

\subsubsection{\texttt{--show\_cells}}
Show all primitives in the design grouped by domain. Only cells in the domains
specified by --domain are shown. Flip-flops only fall into the domain of the net
driving their clock ports.  Non-sequential cells such as LUTs may belong to
multiple domains.

\subsubsection{\texttt{--show\_nets}}
Show all nets in the design grouped by domain. Only nets in the domains 
specified by --domain are shown. Nets may fall into multiple domains.

\subsubsection{\texttt{--show\_synchronous}}
Show all synchronous primitives in the design grouped by domain. Only cells in
the domains specified by --domain are shown. Synchronous cells include
flip-flops and BRAMs.  Dual-ported BRAMs may fall into multiple domains.

\subsubsection{\texttt{--show\_asynchronous}}
Show all asynchronous primitives in the design grouped by domain. Only cells in
the domains specified by --domain are shown. Asynchronous cells are all cells
that do not have a clock input.

\subsubsection{\texttt{--show\_gated\_clocks}}
Identify all clocks (if any) that are not driven by a BUFG, DCM or DLL.

\subsubsection{\texttt{--show\_asynchronous\_resets}}
Show all flip-flops in the design that have asynchronus reset/set ports, along
with the nets driving those ports.

\subsubsection{\texttt{--show\_asynchronous\_reset\_cells}}
Show listing of all nets driving asynchronous reset ports, along with
the cells they drive.

\subsubsection{\texttt{--do\_scc\_analysis}}
Show report of SCCs in design.  This option will show the number of SCCs in the
design, as well as the size of each one and the domains contained in the SCC.

\subsubsection{\texttt{--no\_iob\_feedback}}
Use this option to exclude IOBs from the feedback analysis. This is useful when
a top-level inout port is involved in feedback but by design will never be 
written to and read at the same time. Thus there is no \emph{real} feedback.
Using this option may greatly reduce the amount of feedback found in the design.


%
% Words to be ignored by the spell-checker:
%

% LocalWords:  BYU LANL BL-TMR EDIF FPGA TMR OBUF IBUF BUFG IBUFG LUTs
% LocalWords:  SCC SCCs FFs UCF Xilinx java JHDL netlister IOB IBUFs
% LocalWords:  OBUFs logfile INOUT TMR'd tmr txt 
